<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Recommendations - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/doc-standard.recommendations.html">Inglês (English)</a></li>
    <li><a href="../pt-br/doc-standard.recommendations.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="doc-standard.file-formatting.html">Documentation File Formatting</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="doc-standard.html">Zend Framework Documentation Standard</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="project-structure.html">Recommended Project Structure for Zend Framework MVC Applications</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="doc-standard.recommendations" class="section"><div class="info"><h1 class="title">Recommendations</h1></div>
        

        <div class="section" id="doc-standard.recommendations.editors"><div class="info"><h1 class="title">Use editors without autoformatting</h1></div>
            

            <p class="para">
                For editing the documentation, typically you should not use formal
                <acronym class="acronym">XML</acronym> editors. Such editors normally autoformat existing documents
                to fit their own standards and/or do not strictly follow the docbook standard. As
                examples, we have seen them erase the <acronym class="acronym">CDATA</acronym> tags, change 4 space
                separation to tabs or 2 spaces, etc.
            </p>

            <p class="para">
                The style guidelines were written in large part to assist translators in recognizing
                the lines that have changed using normal <strong class="command">diff</strong> tools.
                Autoformatting makes this process more difficult.
            </p>
        </div>

        <div class="section" id="doc-standard.recommendations.images"><div class="info"><h1 class="title">Use Images</h1></div>
            

            <p class="para">
                Good images and diagrams can improve readability and comprehension. Use them
                whenever they will assist in these goals. Images should be placed in the
                <var class="filename">documentation/manual/en/figures/</var> directory, and be named after
                the section identifier in which they occur.
            </p>
        </div>

        <div class="section" id="doc-standard.recommendations.examples"><div class="info"><h1 class="title">Use Case Examples</h1></div>
            

            <p class="para">
                Look for good use cases submitted by the community, especially those posted in
                proposal comments or on one of the mailing lists. Examples often illustrate usage
                far better than the narrative does.
            </p>

            <p class="para">
                When writing your examples for inclusion in the manual, follow
                all coding standards and documentation standards.
            </p>
        </div>

        <div class="section" id="doc-standard.recommendations.phpdoc"><div class="info"><h1 class="title">Avoid Replicating phpdoc Contents</h1></div>
            

            <p class="para">
                The manual is intended to be a reference guide for end-user usage. Replicating
                the phpdoc documentation for internal-use components and classes is not wanted, and
                the narrative should be focussed on usage, not the internal workings. In any case,
                at this time, we would like the documentation teams to focus on translating the
                English manual, not the phpdoc comments.
            </p>
        </div>

        <div class="section" id="doc-standard.recommendations.links"><div class="info"><h1 class="title">Use Links</h1></div>
            

            <p class="para">
                Link to other sections of the manual or to external sources
                instead of recreating documentation.
            </p>

            <p class="para">
                Linking to other sections of the manual may be done using the
                <em class="emphasis">&lt;link&gt;</em> tag (to which you must provide link text).
            </p>

            <pre class="programlisting brush: xml">
&lt;para&gt;
    &quot;Link&quot; links to a section, using descriptive text: &lt;link
        linkend=&quot;doc-standard.recommendations.links&quot;&gt;documentation on
        links&lt;/link&gt;.
&lt;/para&gt;
</pre>


            <p class="para">
                To link to an external resource, use <em class="emphasis">&lt;ulink&gt;</em>:
            </p>

            <pre class="programlisting brush: xml">
&lt;para&gt;
    The &lt;ulink url=&quot;http://framework.zend.com/&quot;&gt;Zend Framework site&lt;/ulink&gt;.
&lt;/para&gt;
</pre>

        </div>
    </div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="doc-standard.file-formatting.html">Documentation File Formatting</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="doc-standard.html">Zend Framework Documentation Standard</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="project-structure.html">Recommended Project Structure for Zend Framework MVC Applications</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="doc-standard.html">Zend Framework Documentation Standard</a></li>
  <li><a href="doc-standard.overview.html">Overview</a></li>
  <li><a href="doc-standard.file-formatting.html">Documentation File Formatting</a></li>
  <li class="active"><a href="doc-standard.recommendations.html">Recommendations</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>